Using bindings

Use bindings to update properties or property attributes of one node with the properties or property attributes of other nodes. Bindings allow nodes to automatically update the values of their properties in response to the changing attributes in other nodes or the occurrence of some external event.

For example, you can:

• Bind the position or size of one node to the position or size of another node. See Tutorial: Making applications with dynamic layout.
• Bind the rotation property field of a node to a property to create a gauge needle you can control by changing the value of a property. See Tutorial: Create gauges.
• Bind the rotation property field of a node to the Scroll Position of a Scroll View node to rotate the node using swiping gestures. See Tutorial: Rotate a 3D model.

The simplest of bindings include binding a node's property to a constant or to one of its own properties. Creating a more complex binding involves binding properties and attributes of one node to that of several different nodes and adding several bindings.

You can create bindings after you add the Bindings property to a node. Blue type marks the properties that are controlled by a binding.

When creating bindings, note that:

• Only bindings to similar data types are valid. For example, you can bind only color to color, vector2 to vector2, and so on.
• Binding takes the value of the last expression, whether it is an assignment, unary or binary operation, or just a constant value or variable itself.
• In bindings you can cast strings between the four fundamental types: integer, float, boolean, and string. Casts between integer and float are implicit and depend on the type of the property that uses the value. Casts to and from string are explicit.

See Bindings expressions reference.

When you write expressions for bindings in the Binding Argument Editor, the fastest and most accurate way to include nodes and their properties in the expression is to drag and drop them from the Properties to the Expression editor in the Binding Argument Editor.

Note that the properties you bind override the properties set in the Properties.

For a list of error messages and their explanations in the Binding Argument Editor, see Troubleshooting bindings.

Creating a simple binding

The simplest of bindings include binding a node's property to a constant or to one of its own properties.

To create a binding:

1. In the Project create and select the node the properties of which you want to bind.
   For example, create a Box and select it.
2. In the Properties add the Bindings property.
   The Binding Argument Editor window opens.
   
3. In the Binding Argument Editor set:
• Property to the property you want to bind.
  For example, to bind any of the transformation attributes, select Layout Transformation.
• Attribute to the property attribute.
  For example, to bind to a scale attribute, select Scale Y.

4. In the Expression editor enter the expression and click Save to apply the binding.
   

   You can apply a binding in these ways:

   • To apply a binding without closing the Binding Argument Editor, click Apply.
     TIP

     When you edit only the binding expression, you can apply a binding by pressing the Shift+Enter keys on the keyboard.

   • To apply a binding and close the Binding Argument Editor, click Save.
     
   
   For example:
   • To bind the scale along the y axis to a constant, enter:
     

     10

     
     When you apply the binding, the scale of the node increases by 10 units on the y axis.
   • To bind the scale on the y axis to a constant, the result of an operation, enter:
     

     MAX(23.2, 45.5)

     
     When you apply the binding, the scale of the node increases by 45.5 units on the y axis.
   • To bind the scale on the y axis to the location along the x axis of this same node, enter:

     {@./LayoutTransformation}.TranslationX*20

     
     When you move the node along the x axis, the scale of the node around the y axis is multiplied by 20.

Creating a more complex binding

A more complex binding involves binding properties of one node to that of several nodes, or using several bindings. In this example, you create three sliders, each setting one of the three light colors.

To create a more complex binding:

1. Create a Sphere, a Point Light, and three Slider components. See Using the Slider nodes and Using the light nodes.
   For example:
   1. In the Project press Alt and right-click Scene and select Sphere.
   2. In the Project press Alt and right-click Scene, select Point Light, and in the Preview place the Point Light above the Sphere.
      
   3. In the Project press Alt and right-click Viewport 2D, select Stack Layout 2D, and in the Properties set its Direction property to Y.
      
   4. In the Assets set Source to Factory Content and drag three Slider components to the Stack Layout 2D.
      
   5. In the Project select each slider in the Stack Layout 2D, press F2, and rename the sliders to Red, Green, and Blue.
      
2. In the Project select the Point Light, in the Properties add the Bindings property.
   The Binding Argument Editor window opens.
3. In the Binding Argument Editor set:
   • Property to Point Light Color and Attribute to Color R.
     This binds to the property of the red color channel of the Point Light.
   • In the Expression editor enter:
     

     {@../../Stack Layout 2D/Red/RangeConcept.Value}/256

     

   Click Save.
4. In the Properties under the binding you created click + Add Binding and repeat the previous step for the Point Light Point Light Color property attributes Color G and Color B, and bind them to the Value property of the remaining two sliders.
   
   In the Preview when you move the knobs of the sliders, the color of the Point Light changes.
   

Using piecewise functions in bindings

You can set how a value of a property changes using a piecewise function. For example, you can set how quickly a needle in a gauge moves: you can set the needle to move faster from values 0 to 100 than it does for values from 100 to 250. See Animate.

To use a piecewise function in bindings to create a gauge needle:

1. Create an Animation Data item. See Animations.
   For example, create an Animation Data item that contains three keyframe points so that you end up with two significantly different segments. For example, create keyframes at:
   • Time 0 with Value 0
   • Time 2 with Value 100
   • Time 10 with Value 250
     
2. In the Project select or create a node for the properties of which you want to use the piecewise function you created in the Animation Data item in the previous step.
   For example, to create a gauge needle create an Empty Node 3D, add to it a Plane, and position the Plane so that you can use the Empty Node 3D to rotate the Plane around its endpoint. See Editing the origin of nodes.
   
3. In the Library > Property Types create the property type you use to control the position of the needle.
   For example, create a property type named Speed and set:
   • Data Type to Float
   • Editor to Slider
   • Lower Bound to 0
   • Upper Bound to 10
   • Slider Step to 0,1

   Click Save.

4. In the Project select the Empty Node 3D, in the Properties click , and add:
   • The property type you created in the previous step.
   • Bindings property.
5. In the Properties click + Add Binding and in the Binding Argument Editor create a binding that controls the position of the Empty Node 3D:
   • Property and Attribute to the property and attribute you want use to position the Empty Node 3D with the expression in the binding. Note that you can animate only a single attribute.
   • In the Expression editor enter the expression that sets the position of the Empty Node 3D.
     For example, enter:
     

     CreateRotationZ(-{@./Speed})

   
   
   Click Save.
6. In the Properties click + Add Binding and in the Binding Argument Editor create a binding that changes the position of the Empty Node 3D using a piecewise function you defined in the Animation Data item you created in the first step:
   • Property to the property you want to use to control the position with the expression in the binding.
     For example, use the custom property type you created earlier in this procedure.
   • In the Expression editor enter the expression that sets the position of the Empty Node 3D using the piecewise function. To point to the Animation Data resource you created earlier use either its resource ID or kzb file URL.
     For example, enter:
     

     ANIMATE({@./Speed}, "kzb://<ProjectName>/Animation Data/Animation")

   
   
   Click Save.
   When you change the value of the Speed property in the Empty Node 3D the needle moves. Notice that the position of the needle is defined by the piecewise function you defined in the Animation Data item: the needle moves in larger increments when the value of the Speed property is between 0 and 2, and in smaller increments when the value of the property is between 2 and 10.

Using bindings as an alternative to property inheritance

You can use bindings as an alternative to inheritance. You can use inheritance for defining a property in a parent so that it is inherited by a child node, but it works only when a property is inheritable and it is acceptable to have the property inherited by all child nodes. See Property system.

To use bindings as an alternative to inheritance:

1. Create a custom property and add it to the node to which you want to create a binding.
2. In the Project select the node to which you want to add a binding and in the Properties add the Bindings property.
3. In the Binding Argument Editor set:
   1. Property and Attribute to the property and attribute you want to bind.
   2. In the Expression editor enter the expression to include the custom property you created in the beginning of this procedure.
   3. Click Save.

Using bindings in the API

For details, see the Binding class in the API reference.

See also

Bindings expressions reference

Finding invalid project items

Troubleshooting bindings

Open topic with navigation